<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Finding Steps</title>
</head>

<body>

<h2>Finding Steps</h2>

<p>The matching of textual steps to Java methods, each representing
an executable step, is a key concept in creating a <a
	href="http://en.wikipedia.org/wiki/Domain-specific_language">Domain-Specific
Language (DSL)</a>. Once a DSL has been defined, we need a way to display
the "grammar" of the DSL to enable to story writer to exercise that
grammar in writing the scenarios.</p>

<p>JBehave centers around the matching of textual steps with Java
methods contained in steps instances. Each annotated method in the steps instances
corresponds to a <a
	href="javadoc/core/org/jbehave/core/steps/StepCandidate.html">StepCandidate</a>,
which is responsible for the matching and for the creation of an
executable step.</p>

<p>When the number of CandidateSteps instances grows, it can become
more difficult to find a matching step candidates. In this case, it is
useful to make use of the <a
	href="javadoc/core/org/jbehave/core/steps/StepFinder.html">StepFinder</a>
to report matching candidates. JBehave provides the concept of <a
	href="javadoc/core/org/jbehave/core/steps/Stepdoc.html">Stepdoc</a>, as
a documentation facade around a single StepCandidate, i.e. a single
annotated method in the steps instance. This documentation
includes:</p>
<ul>
	<li>the associated annotation in the method of the steps instance
	class</li>
    <li>the method in the steps instance class</li>
	<li>the pattern to match the step candidate that is configured in
	the annotation</li>
	<li>the alias patterns for the step candidate (optional)</li>
</ul>

<p>To find and report matchings Stepdocs via the Embedder:</p>
<pre class="brush: java">
    Embedder embedder = new Embedder();
    embedder.useConfiguration(...); // specify your configuration
    embedder.useCandidateSteps(...); // create your CandidateSteps using the InjectableStepsFactory from your steps instances 
    embedder.reportMatchingStepocs("Given a step that I'm looking to match")
</pre>
<p>The result of the search would by default be output to console,
e.g.:</p>
<pre class="brush: plain">
Step 'When traders are subset to ".*y" by name' is matched by annotated methods:
When traders are subset to "%regex" by name
When traders are filtered by "%regex"
org.jbehave.examples.trader.TraderSteps.subsetTradersByName(java.lang.String)
from steps instances:
org.jbehave.examples.trader.TraderSteps
org.jbehave.examples.trader.BeforeAfterSteps
</pre>

<p>And if a match is not found:</p>
<pre class="brush: plain">
Step 'Given a step that I'm looking to match' is not matched by any method
from steps instances:
org.jbehave.examples.trader.TraderSteps
org.jbehave.examples.trader.BeforeAfterSteps
</pre>

<p>To change the output from console, you can configure the <b>StepdocReporter</b>
to output to any print stream:</p>
<pre class="brush: java">
   embedder.configuration().useStepdocReporter(new PrintStreamStepReporter(...)); // defaults to System.out
</pre>

<h2>Reporting Stepdocs As Embeddables</h2>

<p>A recurrent use case is to report the steps that are configured in the Embeddables used to run the stories.</p>

<h3>Using Ant Task</h3>

<script type="syntaxhighlighter" class="brush: xml">
<![CDATA[

    <taskdef name="reportStepdocsAsEmbeddables" classname="org.jbehave.ant.ReportStepdocsAsEmbeddables"
      classpathref="story.classpath" />
    <reportStepdocsAsEmbeddables includes="**/stories/*.java"/>
      
]]>
</script>

<p>Remember to include <b>jbehave-ant</b> to your runtime classpath.</p>

<h3>Using Maven Goal</h3>

<script type="syntaxhighlighter" class="brush: xml">
<![CDATA[
   <plugin>
        <groupId>org.jbehave</groupId>
        <artifactId>jbehave-maven-plugin</artifactId>
        <version>[version]</version>
        <executions>
          <execution>
            <id>report-stepdocs</id>
            <phase>integration-test</phase>
            <configuration>
              <includes>
                <include>**/stories/*.java</include>
              </includes>
            </configuration>
            <goals>
              <goal>report-stepdocs-as-embeddables</goal>
            </goals>
          </execution>
        </executions>
    </plugin>
]]>
</script>

<div class="clear">
<hr />
</div>

</body>
</html>
